/*
 * Copyright (C) 2023 Huawei Device Co., Ltd.
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * @addtogroup Image_NativeModule
 * @{
 *
 * @brief 提供图片处理的相关能力，包括图片编解码、从Native层获取图片数据等。\n
 * 
 * 使用该模块的接口，无需通过JS接口导入，可直接使用NDK完成功能开发。
 * @since 12
 */

/**
 * @file image_source_native.h
 *
 * @brief 图片解码API。
 *
 * @library libimage_source.so
 * @kit ImageKit
 * @include <multimedia/image_framework/image/image_source_native.h>
 * @syscap SystemCapability.Multimedia.Image.ImageSource
 * @since 12
 */

#ifndef INTERFACES_KITS_NATIVE_INCLUDE_IMAGE_IMAGE_SOURCE_NATIVE_H_
#define INTERFACES_KITS_NATIVE_INCLUDE_IMAGE_IMAGE_SOURCE_NATIVE_H_
#include "image_common.h"

#include "pixelmap_native.h"
#include "picture_native.h"
#include "rawfile/raw_file.h"

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief OH_ImageSourceNative是native层封装的ImageSource结构体，用于创建图片数据。OH_ImageSourceNative结构体不可直接操作，而是采用函数调用方式创建、释放结构体以及操作具体字段。\n
 * 有多种方式可创建OH_ImageSourceNative。\n
 * 释放OH_ImageSourceNative对象使用{@link OH_ImageSourceNative_Release}函数。
 * @since 12
 */
struct OH_ImageSourceNative;
typedef struct OH_ImageSourceNative OH_ImageSourceNative;

/**
 * @brief OH_ImageSource_Info是native层封装的ImageSource信息结构体，OH_ImageSource_Info结构体不可直接操作，而是采用函数调用方式创建、释放结构体以及操作具体字段。\n
 * 创建OH_ImageSource_Info对象使用{@link OH_ImageSourceInfo_Create}函数。\n
 * 释放OH_ImageSource_Info对象使用{@link OH_ImageSourceInfo_Release}函数。
 *
 * @since 12
 */
struct OH_ImageSource_Info;
typedef struct OH_ImageSource_Info OH_ImageSource_Info;

/**
 * @brief Picture解码参数结构体。
 * 通过{@link OH_DecodingOptionsForPicture_Create}获取。
 *
 * @since 13
 */
 struct OH_DecodingOptionsForPicture;

 /**
  * @brief Picture解码参数结构体。
  * 通过{@link OH_DecodingOptionsForPicture_Create}获取。
  * @since 13
  */
 typedef struct OH_DecodingOptionsForPicture OH_DecodingOptionsForPicture;

/**
 * @brief 解码指定期望动态范围。
 *
 * @since 12
 */
typedef enum {
    /*
    * 根据图片自适应处理。
    */
    IMAGE_DYNAMIC_RANGE_AUTO = 0,
    /*
    * 标准动态范围。
    */
    IMAGE_DYNAMIC_RANGE_SDR = 1,
    /*
    * 高动态范围。
    */
    IMAGE_DYNAMIC_RANGE_HDR = 2,
} IMAGE_DYNAMIC_RANGE;

/**
 * @brief 用于分配PixelMap内存的分配器类型。
 *
 * @since 15
 */
typedef enum {
   /**
    * 由系统决定使用DMA内存或共享内存来创建PixelMap。
    */
    IMAGE_ALLOCATOR_TYPE_AUTO = 0,
   /**
    * 使用DMA内存来创建PixelMap。
    */
    IMAGE_ALLOCATOR_TYPE_DMA = 1,
   /**
    * 使用共享内存来创建PixelMap。
    */
    IMAGE_ALLOCATOR_TYPE_SHARE_MEMORY = 2,
} IMAGE_ALLOCATOR_TYPE;

/**
 * @brief 在同时指定desiredSize和desiredRegion时执行裁剪和缩放的策略。\n
 * 如果在配置解码选项{@link OH_DecodingOptions}时，未填入参数Image_CropAndScaleStrategy，并且同时设置了desiredRegion和desiredSize，
 * 由于系统对于不同图片格式采用的解码算法不同，最终解码效果将略有差异。\n
 *
 * 例如原始图片大小200x200，传入desiredSize:{width: 150, height: 150}，desiredRegion:{x: 0, y: 0, width: 100, height: 100}，
 * 即预期解码原图左上角1/4区域，最终将pixelMap大小缩放至150x150返回。\n
 * 
 * 对于jpeg、webp图片（部分dng图片解码时会优先解码图片中的jpeg预览图，在此场景下也会被视为jpeg图片格式）会先进行下采样，例如按照7/8下采样，
 * 再基于175x175的图片大小进行区域裁剪，因此最终的区域内容稍大于原图的左上角1/4区域。\n
 * 
 * 对于svg图片，由于是矢量图，可以任意缩放不损失清晰度，在解码时会根据desiredSize与原图Size的比例选择缩放比例，在基于缩放后的图片大小进行区域裁剪，因此最终返回的解码区域会有所差异。\n
 *
 * 针对该场景，建议在解码选项同时设置了desiredRegion与desiredSize时，参数Image_CropAndScaleStrategy应传入CROP_FIRST参数保证效果一致。
 *
 * @since 18
 */
typedef enum {
    /**
     * 先裁剪，后缩放。
     */
    IMAGE_CROP_AND_SCALE_STRATEGY_SCALE_FIRST = 1,

    /**
     * 先缩放，后裁剪。
     */
    IMAGE_CROP_AND_SCALE_STRATEGY_CROP_FIRST = 2,
} Image_CropAndScaleStrategy;

/**
 * @brief 创建OH_ImageSource_Info指针。
 *
 * @param info 被操作的OH_ImageSource_Info指针。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 12
 */
Image_ErrorCode OH_ImageSourceInfo_Create(OH_ImageSource_Info **info);

/**
 * @brief 获取图片的宽。
 *
 * @param info 被操作的OH_ImageSource_Info指针。
 * @param width 图片的宽，单位：像素。
 * @return IMAGE_SUCCESS：执行成功。\n 
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 12
 */
Image_ErrorCode OH_ImageSourceInfo_GetWidth(OH_ImageSource_Info *info, uint32_t *width);

/**
 * @brief 获取图片的高。
 *
 * @param info 被操作的OH_ImageSource_Info指针。
 * @param height 图片的高，单位：像素高
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 12
 */
Image_ErrorCode OH_ImageSourceInfo_GetHeight(OH_ImageSource_Info *info, uint32_t *height);

/**
 * @brief 获取图片是否为高动态范围的信息。
 *
 * @param info 被操作的OH_ImageSource_Info指针。
 * @param isHdr 是否为hdr的布尔值。
 * @return IMAGE_SUCCESS：执行成功。\n 
 *         IMAGE_BAD_PARAMETER：参数校验错误。
 * @since 12
 */
Image_ErrorCode OH_ImageSourceInfo_GetDynamicRange(OH_ImageSource_Info *info, bool *isHdr);

/**
 * @brief 获取图片源的MIME类型。
 *
 * @param info OH_ImageSource_Info指针。
 * @param mimetype 图片源的MIME类型。
 * @return IMAGE_SUCCESS：执行成功。\n 
 *         IMAGE_SOURCE_INVALID_PARAMETER：参数错误，INFO或者MIME类型为空。
 * @since 20
 */
Image_ErrorCode OH_ImageSourceInfo_GetMimetype(OH_ImageSource_Info *info, Image_MimeType *mimetype);

/**
 * @brief 释放OH_ImageSource_Info指针。
 *
 * @param info 被操作的OH_ImageSource_Info指针。
 * @return IMAGE_SUCCESS：执行成功。\n 
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 12
 */
Image_ErrorCode OH_ImageSourceInfo_Release(OH_ImageSource_Info *info);

/**
 * @brief OH_DecodingOptions是native层封装的解码选项参数结构体，用于设置解码选项参数，在创建Pixelmap时作为入参传入，详细信息见{@link OH_ImageSourceNative_CreatePixelmap)。\n
 * OH_DecodingOptions结构体不可直接操作，而是采用函数调用方式创建、释放结构体以及操作具体字段。\n
 * 创建OH_DecodingOptions对象使用{@link OH_DecodingOptions_Create}函数。\n
 * 释放OH_DecodingOptions对象使用{@link OH_DecodingOptions_Release}函数。
 *
 * @since 12
 */
typedef struct OH_DecodingOptions OH_DecodingOptions;

/**
 * @brief 创建OH_DecodingOptions指针。
 *
 * @param  options 被操作的OH_DecodingOptions指针。
 * @return IMAGE_SUCCESS：执行成功。\n 
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 12
 */
Image_ErrorCode OH_DecodingOptions_Create(OH_DecodingOptions **options);

/**
 * @brief 获取pixel格式。
 *
 * @param  options 被操作的OH_DecodingOptions指针。
 * @param pixelFormat pixel格式{@link PIXEL_FORMAT}。
 * @return IMAGE_SUCCESS：执行成功。\n 
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 12
 */
Image_ErrorCode OH_DecodingOptions_GetPixelFormat(OH_DecodingOptions *options,
    int32_t *pixelFormat);

/**
 * @brief 设置pixel格式。
 *
 * @param  options 被操作的OH_DecodingOptions指针。
 * @param pixelFormat pixel格式{@link PIXEL_FORMAT}。
 * @return IMAGE_SUCCESS：执行成功。\n 
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 12
 */
Image_ErrorCode OH_DecodingOptions_SetPixelFormat(OH_DecodingOptions *options,
    int32_t pixelFormat);

/**
 * @brief 获取解码图片序号。
 *
 * @param  options 被操作的OH_DecodingOptions指针。
 * @param index 解码图片序号。
 * @return IMAGE_SUCCESS：执行成功。\n 
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 12
 */
Image_ErrorCode OH_DecodingOptions_GetIndex(OH_DecodingOptions *options, uint32_t *index);

/**
 * @brief 设置解码图片序号。
 *
 * @param  options 被操作的OH_DecodingOptions指针。
 * @param index 解码图片序号。
 * @return IMAGE_SUCCESS：执行成功。\n 
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 12
 */
Image_ErrorCode OH_DecodingOptions_SetIndex(OH_DecodingOptions *options, uint32_t index);

/**
 * @brief 获取旋转角度。
 *
 * @param  options 被操作的OH_DecodingOptions指针。
 * @param rotate 旋转角度，单位为deg。
 * @return IMAGE_SUCCESS：执行成功。\n 
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 12
 */
Image_ErrorCode OH_DecodingOptions_GetRotate(OH_DecodingOptions *options, float *rotate);

/**
 * @brief 设置旋转角度。
 *
 * @param  options 被操作的OH_DecodingOptions指针。
 * @param rotate 旋转角度，单位为deg。
 * @return IMAGE_SUCCESS：执行成功。\n 
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 12
 */
Image_ErrorCode OH_DecodingOptions_SetRotate(OH_DecodingOptions *options, float rotate);

/**
 * @brief 获取期望输出大小。
 *
 * @param  options 被操作的OH_DecodingOptions指针。
 * @param desiredSize 期望输出大小。
 * @return IMAGE_SUCCESS：执行成功。\n 
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 12
 */
Image_ErrorCode OH_DecodingOptions_GetDesiredSize(OH_DecodingOptions *options,
    Image_Size *desiredSize);

/**
 * @brief 设置期望输出大小。
 *
 * @param  options 被操作的OH_DecodingOptions指针。
 * @param desiredSize 期望输出大小。
 * @return IMAGE_SUCCESS：执行成功。\n 
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 12
 */
Image_ErrorCode OH_DecodingOptions_SetDesiredSize(OH_DecodingOptions *options,
    Image_Size *desiredSize);

/**
 * @brief 获取解码区域。\n
 * 由于对应SetDesiredRegion接口无法满足区域解码诉求，从API 19开始，推荐配套使用{@link OH_DecodingOptions_GetCropRegion}接口替代。
 *
 * @param  options 被操作的OH_DecodingOptions指针。
 * @param desiredRegion 解码区域。
 * @return IMAGE_SUCCESS：执行成功。\n 
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 12
 */
Image_ErrorCode OH_DecodingOptions_GetDesiredRegion(OH_DecodingOptions *options,
    Image_Region *desiredRegion);

/**
 * @brief 设置解码区域。\n
 * 实际解码结果会按照原图解码，无区域解码效果。从API 19开始，推荐使用接口{@link OH_DecodingOptions_SetCropRegion}替代。
 *
 * @param  options 被操作的OH_DecodingOptions指针。
 * @param desiredRegion 解码区域。
 * @return IMAGE_SUCCESS：执行成功。\n 
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 12
 */
Image_ErrorCode OH_DecodingOptions_SetDesiredRegion(OH_DecodingOptions *options,
    Image_Region *desiredRegion);

/**
 * @brief 获取解码时设置的期望动态范围。
 *
 * @param options 被操作的OH_DecodingOptions指针。
 * @param desiredDynamicRange 期望的动态范围值{@link IMAGE_DYNAMIC_RANGE}。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_BAD_PARAMETER：参数校验错误。
 * @since 12
 */
Image_ErrorCode OH_DecodingOptions_GetDesiredDynamicRange(OH_DecodingOptions *options,
    int32_t *desiredDynamicRange);

/**
 * @brief 设置解码时的期望动态范围。
 *
 * @param options 被操作的OH_DecodingOptions指针。
 * @param desiredDynamicRange 期望的动态范围值{@link IMAGE_DYNAMIC_RANGE}。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_BAD_PARAMETER：参数校验错误。
 * @since 12
 */
Image_ErrorCode OH_DecodingOptions_SetDesiredDynamicRange(OH_DecodingOptions *options,
    int32_t desiredDynamicRange);

/**
 * @brief 获取解码参数中设置的色彩空间。
 *
 * @param options 解码参数。
 * @param colorSpace 解码参数中设置的色彩空间，参考{@link ColorSpaceName}。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_SOURCE_INVALID_PARAMETER：参数错误。options或colorSpace为空。
 * @since 20
 */
Image_ErrorCode OH_DecodingOptions_GetDesiredColorSpace(OH_DecodingOptions *options, int32_t *colorSpace);

/**
 * @brief 设置解码期望得到的色彩空间。
 *
 * @param options 解码参数。
 * @param colorSpace 期望的色彩空间，参考{@link ColorSpaceName}。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_SOURCE_INVALID_PARAMETER：参数错误。options为空，或者传入了不支持的colorSpace。
 * @since 20
 */
Image_ErrorCode OH_DecodingOptions_SetDesiredColorSpace(OH_DecodingOptions *options, int32_t colorSpace);

/**
 * @brief 设置解码选项的裁剪和缩放策略。
 *
 * @param options 被操作的OH_DecodingOptions指针。
 * @param cropAndScaleStrategy 在同时指定desiredSize和desiredRegion时执行裁剪和缩放的策略。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_BAD_PARAMETER：options空指针或者cropAndScaleStrategy取值不在Image_CropAndScaleStrategy枚举值定义之中。
 * @since 18
 */
Image_ErrorCode OH_DecodingOptions_SetCropAndScaleStrategy(OH_DecodingOptions *options,
    int32_t cropAndScaleStrategy);

/**
 * @brief 获取解码选项的裁剪和缩放策略。
 *
 * @param options 被操作的OH_DecodingOptions指针。
 * @param cropAndScaleStrategy 指向在同时指定desiredSize和desiredRegion时执行裁剪和缩放策略的指针。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_BAD_PARAMETER：options或者cropAndScaleStrategy为空指针。
 * @since 18
 */
Image_ErrorCode OH_DecodingOptions_GetCropAndScaleStrategy(OH_DecodingOptions *options,
    int32_t *cropAndScaleStrategy);

/**
 * @brief 获取解码参数中的裁剪区域。
 *
 * @param options 指向解码参数指针。
 * @param cropRegion 指向要裁剪的目标区域指针。
 * @return IMAGE_SUCCESS：操作成功。\n
 *         IMAGE_SOURCE_INVALID_PARAMETER：options或cropRegion为空。
 * @since 19
 */
Image_ErrorCode OH_DecodingOptions_GetCropRegion(OH_DecodingOptions *options, Image_Region *cropRegion);

/**
 * @brief 设置解码参数中的裁剪区域。
 *
 * @param options 指向解码参数指针。
 * @param cropRegion 指向要裁剪的目标区域指针。
 * @return IMAGE_SUCCESS：操作成功。\n
 *         IMAGE_SOURCE_INVALID_PARAMETER：options或cropRegion为空。
 * @since 19
 */
Image_ErrorCode OH_DecodingOptions_SetCropRegion(OH_DecodingOptions *options, Image_Region *cropRegion);

/**
 * @brief 释放OH_DecodingOptions指针。
 *
 * @param  options 被操作的OH_DecodingOptions指针。
 * @return IMAGE_SUCCESS：执行成功。\n 
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 12
 */
Image_ErrorCode OH_DecodingOptions_Release(OH_DecodingOptions *options);

/**
 * @brief 通过uri创建OH_ImageSourceNative指针。
 *
 * @param uri 指向图像源URI的指针。只接受文件URI或Base64 URI。当前文件资源只支持绝对路径。
 * @param uriSize URI长度。
 * @param res 指向c++本地层创建的OH_ImageSourceNative对象的指针。
 * @return IMAGE_SUCCESS：执行成功。\n 
 *         IMAGE_BAD_PARAMETER：参数错误。\n
 *         IMAGE_BAD_SOURCE：解码数据源异常。
 * @since 12
 */
Image_ErrorCode OH_ImageSourceNative_CreateFromUri(char *uri, size_t uriSize, OH_ImageSourceNative **res);

/**
 * @brief 通过fd创建OH_ImageSourceNative指针。
 *
 * @param fd 文件描述符fd。
 * @param res 指向c++本地层创建的OH_ImageSourceNative对象的指针。
 * @return IMAGE_SUCCESS：执行成功。\n 
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 12
 */
Image_ErrorCode OH_ImageSourceNative_CreateFromFd(int32_t fd, OH_ImageSourceNative **res);

/**
 * @brief 通过缓冲区数据创建OH_ImageSourceNative指针。\n
 * data数据应该是未解码的数据，不要传入类似于RBGA，YUV的像素buffer数据，如果想通过像素buffer数据创建pixelMap，可以调用{@link OH_PixelmapNative_CreatePixelmap}这一类接口。
 *
 * @param data 图像缓冲区数据。
 * @param dataSize 图像缓冲区数据长度。
 * @param res 指向c++本地层创建的OH_ImageSourceNative对象的指针。
 * @return IMAGE_SUCCESS：执行成功。\n 
 *         IMAGE_BAD_PARAMETER：参数错误。\n
 *         IMAGE_BAD_SOURCE：解码数据源异常。
 * @since 12
 */
Image_ErrorCode OH_ImageSourceNative_CreateFromData(uint8_t *data, size_t dataSize, OH_ImageSourceNative **res);

/**
 * @brief 由数据缓存创建图片源。传入的数据缓存将在图片源对象中直接访问，在图片源对象的声明周期内，数据缓存需要保持可用。
 *
 * @param data 数据缓存指针。
 * @param datalength 数据缓存长度。
 * @param imageSource 图片源的二级指针。
 * @return IMAGE_SUCCESS：执行成功。\n 
 *         IMAGE_SOURCE_INVALID_PARAMETER：data或imageSource是空指针，datalength为0。
 * @since 20
 */
Image_ErrorCode OH_ImageSourceNative_CreateFromDataWithUserBuffer(uint8_t *data, size_t datalength,
    OH_ImageSourceNative **imageSource);

/**
 * @brief 通过图像资源文件的RawFileDescriptor创建OH_ImageSourceNative指针。
 *
 * @param rawFile 指示raw文件的文件描述符。
 * @param res 指向c++本地层创建的OH_ImageSourceNative对象的指针。
 * @return IMAGE_SUCCESS：执行成功。\n 
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 12
 */
Image_ErrorCode OH_ImageSourceNative_CreateFromRawFile(RawFileDescriptor *rawFile, OH_ImageSourceNative **res);

/**
 * @brief 通过图片解码参数创建OH_PixelmapNative指针。
 *
 * @param source 被操作的OH_ImageSourceNative指针。
 * @param options 解码参数。
 * @param pixelmap 指向c++本地层创建的OH_PixelmapNative对象的指针。
 * @return IMAGE_SUCCESS：执行成功。\n 
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 12
 */
Image_ErrorCode OH_ImageSourceNative_CreatePixelmap(OH_ImageSourceNative *source, OH_DecodingOptions *options,
    OH_PixelmapNative **pixelmap);

/**
 * @brief 根据解码参数创建一个PixelMap，PixelMap使用的内存类型可以通过allocatorType来指定。\n
 * 默认情况下，系统会根据图像类型、图像大小、平台能力等选择内存类型。在处理通过此接口返回的PixelMap时，请始终考虑步幅（stride）的影响。
 *
 * @param source 被操作的OH_ImageSourceNative指针。
 * @param options 解码参数。
 * @param allocator 指示返回的PixelMap将使用哪种内存类型。
 * @param pixelmap 指向c++本地层创建的OH_PixelmapNative对象的指针。
 * @return IMAGE_SUCCESS：执行成功。\n 
 *         IMAGE_BAD_PARAMETER：参数错误。\n
 *         IMAGE_BAD_SOURCE：数据源异常。\n
 *         IMAGE_SOURCE_UNSUPPORTED_MIME_TYPE：不支持的MIME类型。\n
 *         IMAGE_SOURCE_TOO_LARGE：图像过大。\n
 *         IMAGE_SOURCE_UNSUPPORTED_ALLOCATOR_TYPE：不支持的分配器类型。例如，使用共享内存解码HDR图像，因为只有DMA支持HDR元数据。\n
 *         IMAGE_SOURCE_UNSUPPORTED_OPTIONS：不支持的选项。例如，无法将图像转换为所需的像素格式。\n
 *         IMAGE_DECODE_FAILED：解码失败。\n
 *         IMAGE_SOURCE_ALLOC_FAILED：内存分配失败。
 * @since 15
 */
Image_ErrorCode OH_ImageSourceNative_CreatePixelmapUsingAllocator(OH_ImageSourceNative *source,
    OH_DecodingOptions *options, IMAGE_ALLOCATOR_TYPE allocator, OH_PixelmapNative **pixelmap);

/**
 * @brief 通过图片解码参数创建OH_PixelmapNative数组。\n
 * 注意，此接口会一次性解码全部帧，当帧数过多或单帧图像过大时，会占用较大内存，造成系统内存紧张，此种情况推荐使用Image组件显示动图，Image组件采用逐帧解码，占用内存比此接口少。
 *
 * @param source 被操作的OH_ImageSourceNative指针。
 * @param  options 解码参数。
 * @param resVecPixMap[] 指向c++本地层创建的OH_PixelmapNative对象的指针数组。
 * @param size 数组长度。 用户可以使用{@link OH_ImageSourceNative_GetFrameCount}获取。
 * @return IMAGE_SUCCESS：执行成功。\n 
 *         IMAGE_BAD_PARAMETER：参数错误。\n
 *         IMAGE_UNSUPPORTED_OPERATION：操作不支持。
 * @since 12
 */
Image_ErrorCode OH_ImageSourceNative_CreatePixelmapList(OH_ImageSourceNative *source, OH_DecodingOptions *options,
    OH_PixelmapNative *resVecPixMap[], size_t size);

/**
 * @brief 通过图片解码创建OH_PictureNative指针。
 *
 * @param source 被操作的OH_ImageSourceNative指针。
 * @param options 解码参数。
 * @param picture 指向c++本地层创建的OH_PictureNative对象的指针。
 * @return IMAGE_SUCCESS：执行成功。\n 
 *         IMAGE_BAD_PARAMETER：参数错误。\n
 *         IMAGE_DECODE_FAILED：解码失败。
 * @since 13
 */
Image_ErrorCode OH_ImageSourceNative_CreatePicture(OH_ImageSourceNative *source, OH_DecodingOptionsForPicture *options,
    OH_PictureNative **picture);

/**
 * @brief 通过指定序号的图片解码创建OH_PictureNative指针。
 *
 * @param source 被操作的OH_ImageSourceNative指针。
 * @param index 解码图片序号。
 * @param picture 指向c++本地层创建的OH_PictureNative对象的指针。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_BAD_SOURCE：数据源异常。\n
 *         IMAGE_SOURCE_UNSUPPORTED_MIME_TYPE：不支持的MIME类型。\n
 *         IMAGE_SOURCE_TOO_LARGE：图像过大。\n
 *         IMAGE_SOURCE_UNSUPPORTED_OPTIONS：不支持的选项。例如，无效的图片序号。\n
 *         IMAGE_DECODE_FAILED：解码失败。
 * @since 20
 */
Image_ErrorCode OH_ImageSourceNative_CreatePictureAtIndex(OH_ImageSourceNative *source, uint32_t index,
    OH_PictureNative **picture);

/**
 * @brief 获取图像延迟时间数组。
 *
 * @param source 被操作的OH_ImageSourceNative指针。
 * @param delayTimeList 指向获得的延迟时间列表的指针。它不能是空指针。
 * @param size delayTimeList的大小。用户可以从{@link OH_ImageSourceNative_GetFrameCount}获得大小。
 * @return IMAGE_SUCCESS：执行成功。\n 
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 12
 */
Image_ErrorCode OH_ImageSourceNative_GetDelayTimeList(OH_ImageSourceNative *source, int32_t *delayTimeList, size_t size);

/**
 * @brief 获取指定序号的图片信息。
 *
 * @param source 被操作的OH_ImageSourceNative指针。
 * @param index 图片序号。对GIF图片可传入[0,N-1],N表示GIF的帧数。对只有一帧数据的图片格式，可传入0。
 * @param info 指向获取的图像源信息的OH_ImageSource_Info指针。
 * @return IMAGE_SUCCESS：执行成功。\n 
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 12
 */
Image_ErrorCode OH_ImageSourceNative_GetImageInfo(OH_ImageSourceNative *source, int32_t index,
    OH_ImageSource_Info *info);

/**
 * @brief 获取图片指定属性键的值。
 *
 * @param source 被操作的OH_ImageSourceNative指针。
 * @param key 指示指向属性的指针，详情请参见{@link Image_String}，key的取值范围参考OHOS_IMAGE_PROPERTY_XXX定义。
 * 使用ImageSource后释放，参见{@link OH_ImageSourceNative_Release}。
 * @param value 指向获取的值的指针。用户可以传入一个空指针和零大小，
 * 我们将分配内存，但用户必须在使用后释放内存。
 * @return IMAGE_SUCCESS：执行成功。\n 
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 12
 */
Image_ErrorCode OH_ImageSourceNative_GetImageProperty(OH_ImageSourceNative *source, Image_String *key,
    Image_String *value);

/**
 * @brief 获取图像属性值。输出的value.data以字符串结束符结尾。
 *
 * @param source 指向ImageSource的指针。
 * @param key 指向属性键的指针。
 * @param value 指向属性值的指针（输出参数）。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_SOURCE_INVALID_PARAMETER：source、key或value为空。
 * @since 19
 */
Image_ErrorCode OH_ImageSourceNative_GetImagePropertyWithNull(OH_ImageSourceNative *source, Image_String *key,
    Image_String *value);

/**
 * @brief 通过指定的键修改图片属性的值。
 * @param source 被操作的OH_ImageSourceNative指针。
 * @param key 指向属性键的指针，详情请参见{@link Image_String}，key是一个exif常数。
 * 使用ImageSource后释放，参见{@link OH_ImageSourceNative_Release}。
 * @param value 需要修改的属性值。
 * @return IMAGE_SUCCESS：执行成功。\n 
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 12
 */
Image_ErrorCode OH_ImageSourceNative_ModifyImageProperty(OH_ImageSourceNative *source, Image_String *key,
    Image_String *value);

/**
 * @brief 获取图像帧数。
 *
 * @param source 被操作的OH_ImageSourceNative指针。
 * @param frameCount 图像帧数。
 * @return IMAGE_SUCCESS：执行成功。\n 
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 12
 */
Image_ErrorCode OH_ImageSourceNative_GetFrameCount(OH_ImageSourceNative *source, uint32_t *frameCount);

/**
 * @brief 获取支持解码的图片格式。
 *
 * @param supportedFormats 支持解码的图片格式。
 * @param length 数组长度。
 * @return IMAGE_SUCCESS：操作成功。\n
 *         IMAGE_SOURCE_INVALID_PARAMETER：参数异常，supportedFormats或length为空。
 * @since 20
 */
Image_ErrorCode OH_ImageSourceNative_GetSupportedFormats(Image_MimeType **supportedFormats, size_t *length);

/**
 * @brief 释放OH_ImageSourceNative指针。
 *
 * @param source 要释放的OH_ImageSourceNative指针。
 * @return IMAGE_SUCCESS：执行成功。\n 
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 12
 */
Image_ErrorCode OH_ImageSourceNative_Release(OH_ImageSourceNative *source);

/**
 * @brief 创建OH_DecodingOptionsForPicture指针。
 *
 * @param options 被操作的OH_DecodingOptionsForPicture指针。
 * @return IMAGE_SUCCESS：执行成功。\n 
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 13
 */
Image_ErrorCode OH_DecodingOptionsForPicture_Create(OH_DecodingOptionsForPicture **options);

/**
 * @brief 获取解码时设置的期望辅助图（期望解码出的picture包含的辅助图）。
 *
 * @param options 被操作的OH_DecodingOptionsForPicture指针。
 * @param desiredAuxiliaryPictures 解码选项中的期望辅助图。
 * @param length 期望辅助图长度。
 * @return IMAGE_SUCCESS：执行成功。\n 
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 13
 */
Image_ErrorCode OH_DecodingOptionsForPicture_GetDesiredAuxiliaryPictures(OH_DecodingOptionsForPicture *options,
    Image_AuxiliaryPictureType **desiredAuxiliaryPictures, size_t *length);

/**
 * @brief 设置解码选项中的期望辅助图。
 *
 * @param options 被操作的OH_DecodingOptionsForPicture指针。
 * @param desiredAuxiliaryPictures 将要设置的期望辅助图。
 * @param length 期望辅助图长度。
 * @return IMAGE_SUCCESS：执行成功。\n 
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 13
 */
Image_ErrorCode OH_DecodingOptionsForPicture_SetDesiredAuxiliaryPictures(OH_DecodingOptionsForPicture *options,
    Image_AuxiliaryPictureType *desiredAuxiliaryPictures, size_t length);

/**
 * @brief 释放OH_DecodingOptionsForPicture指针。
 *
 * @param options 要释放的OH_DecodingOptionsForPicture指针。
 * @return IMAGE_SUCCESS：执行成功。\n 
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 13
 */
Image_ErrorCode OH_DecodingOptionsForPicture_Release(OH_DecodingOptionsForPicture *options);
#ifdef __cplusplus
};
#endif
/** @} */
#endif // INTERFACES_KITS_NATIVE_INCLUDE_IMAGE_IMAGE_SOURCE_NATIVE_H_